<html><head><title>Structures</title></head>
<body bgcolor="#FFFFDF" link="#009999" vlink="#006666" alink="#006666">
<font face="Arial" size="2"><p align="center"><b><font size="5">Structures</font></b></p>

<br><b>Syntax</b><blockquote><pre><font face="Courier New, Courier, mono"size="2"><b><font color="#006666">Structure</font></b> &#060;name&#062; [<b><font color="#006666">Extends</font></b> &#060;name&#062;] [Align &#060;numeric constant expression&#062;]
  ...
<b><font color="#006666">EndStructure</font></b> 
</font></pre></blockquote>
<b>Description</b><br><blockquote>


<b><font color="#006666">Structure</font></b> is useful to define user type, and access some OS memory areas. Structures can be used 
to enable faster and easier handling of data files. It is very useful as you can group into the same 
object the information which are common. Structures fields are accessed with the <b><font color="#006666">\</font></b> option. Structures 
can be nested. Statics arrays are supported inside structures. <br>
<br>
Dynamic objects like arrays, lists and maps are supported inside structure and are automatically initialized 
when the object using the structure is created. To declare such field, use the following keywords: 
<b><font color="#006666">Array</font></b>, <b><font color="#006666">List</font></b> and <b><font color="#006666">Map</font></b>. <br>
<br>
The optional <b><font color="#006666">Extends</font></b> parameter allows to extends another structure with new fields. All fields 
found in the extended structure will be available in the new structure and will be placed before 
the new fields. This is useful to do basic inheritance of structures. <br>
<br>
For advanced users only. The optional <b><font color="#006666">Align</font></b> parameter allows to adjust alignment between every structure field. The default alignment 
is 1, meaning no alignment. For example, if the alignment is set to 4, every field offset will be on a 4 byte boundary. 
It can help to get more performance while accessing structure fields, but it can use more memory, as some space 
between each fields will be wasted. The special value <font color="#924B72">#PB_Structure_AlignC</font> can be used to align the structure 
as it would be done in language C, useful when <a href="../reference/import_endimport.html">importing</a> C structures to use with API functions. 
<br>
<br>
<a href="../reference/compilerfunctions.html">SizeOf</a> can be used with structures to get the size of the structure and <a href="../reference/compilerfunctions.html">OffsetOf</a> can be used to retrieve 
the index of the specified field. <br>
<br>
Please note, that in structures a static array[] doesn't behave like the normal BASIC array (defined using <a href="../reference/dim.html">Dim</a>) 
to be conform to the C/C++ structure format (to allow direct API structure porting). This means that a[2] will 
allocate an array from 0 to 1 where Dim a(2) will allocate an array from 0 to 2. 
<br>
<br>
When using <a href="../reference/memory.html">pointers</a> in structures, the '*' has to be omitted when using the field, once more to ease API code porting. It can be 
seen as an oddity (and to be honest, it is) but it's like that since the very start of PureBasic and many, many sources rely 
on that so it won't be changed. 
<br>
<br>
When using a lot of structure fields you can use the <a href="../reference/with_endwith.html">With</a> : <a href="../reference/with_endwith.html">EndWith</a> 
keywords to reduce the amount of code to type and ease its readability. 
<br>
<br>
It's possible to perform a full structure copy by using the equal affectation between two structure element of the same type. 
<br>
<br>
<a href="../reference/compilerfunctions.html">ClearStructure</a> can be used to clear a structured memory area. It's for advanced use only, when 
<a href="../reference/memory.html">pointers</a> are involved. <br>


</blockquote><p><b>Example</b></p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> Person
    Name.s
    ForName.s 
    Age.w 
  <b><font color="#006666">EndStructure</font></b>

  <b><font color="#006666">Dim</font></b> <font color="#006666">MyFriends</font>.Person(100)

  <font color="#006666">; Here the position '0' of the array MyFriend()</font>
  <font color="#006666">; will contain one person and it's own information</font>

<font color="#006666">  MyFriends</font>(0)\Name = "Andersson"
<font color="#006666">  MyFriends</font>(0)\Forname = "Richard" 
<font color="#006666">  MyFriends</font>(0)\Age = 32
</font></pre>

</blockquote><p><b>Example:</b> A more complex structure (Nested and static array)</p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> Window
    *NextWindow.Window  <font color="#006666">; Points to another window object</font>
    x.w 
    y.w
    Name.s[10]  <font color="#006666">; 10 Names available (from 0 to 9)</font>
  <b><font color="#006666">EndStructure</font></b>
</font></pre>

</blockquote><p><b>Example:</b> Extended structure</p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> MyPoint
    x.l 
    y.l
  <b><font color="#006666">EndStructure</font></b>

  <b><font color="#006666">Structure</font></b> MyColoredPoint <b><font color="#006666">Extends</font></b> MyPoint
    color.l 
  <b><font color="#006666">EndStructure</font></b>

  ColoredPoint.MyColoredPoint\x = 10
  ColoredPoint.MyColoredPoint\y = 20
  ColoredPoint.MyColoredPoint\color =<font color="#006666"> RGB</font>(255, 0, 0)
</font></pre>


</blockquote><p><b>Example:</b> Structure copy</p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> MyPoint
    x.l 
    y.l
  <b><font color="#006666">EndStructure</font></b>

  LeftPoint.MyPoint\x = 10
  LeftPoint\y = 20
  
  RightPoint.MyPoint = LeftPoint
  
  <b><font color="#006666">Debug</font></b> RightPoint\x
  <b><font color="#006666">Debug</font></b> RightPoint\y
</font></pre>

</blockquote><p><b>Example:</b> Dynamic object</p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> Person
    Name$
    Age.l
    <b><font color="#006666">List</font></b> <font color="#006666">Friends$</font>()
  <b><font color="#006666">EndStructure</font></b>

  John.Person
  John\Name$ = "John"
  John\Age   = 23
  
  <font color="#006666">; Now, add some friends to John</font>
  <font color="#006666">;</font>
<font color="#006666">  AddElement</font>(John\<font color="#006666">Friends$</font>())
  John\<font color="#006666">Friends$</font>() = "Jim"

<font color="#006666">  AddElement</font>(John\<font color="#006666">Friends$</font>())
  John\<font color="#006666">Friends$</font>() = "Monica"
  
  <b><font color="#006666">ForEach</font></b> John\<font color="#006666">Friends$</font>()
    <b><font color="#006666">Debug</font></b> John\<font color="#006666">Friends$</font>()
  <b><font color="#006666">Next</font></b>
</font></pre>


</blockquote>
<br><b>Syntax</b><blockquote><pre><font face="Courier New, Courier, mono"size="2"><b><font color="#006666">StructureUnion</font></b>
  Field1.Type
  Field2.Type
  ...
<b><font color="#006666">EndStructureUnion</font></b>
</font></pre></blockquote>
<b>Description</b><br><blockquote>


Structure union are only useful for advanced programmers who want to save some memory 
by sharing some fields inside the same structure. It's like the 'union' keyword in C/C++. 
<br>
<br>
Note: Each field in the <b><font color="#006666">StructureUnion</font></b> declaration can be of a different 
<a href="../reference/variables.html">type</a>. 

</blockquote><p><b>Example</b></p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> Type
    Name$
    <b><font color="#006666">StructureUnion</font></b>
      Long.l      <font color="#006666">; Each field (Long, Float and Byte) resides at the</font>
      Float.f     <font color="#006666">; same address in memory.</font>
      Byte.b      <font color="#006666">;</font>
    <b><font color="#006666">EndStructureUnion</font></b>
  <b><font color="#006666">EndStructure</font></b>
</font></pre>


</blockquote><p><b>Example:</b> Extended example (date handling)</p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> date
    day.s{2}
    pk1.s{1}
    month.s{2}
    pk2.s{1}
    year.s{4}
  <b><font color="#006666">EndStructure</font></b>
  
  <b><font color="#006666">Structure</font></b> date2
    <b><font color="#006666">StructureUnion</font></b>
      s.s{10}
      d.date
    <b><font color="#006666">EndStructureUnion</font></b>
  <b><font color="#006666">EndStructure</font></b>
  
  <b><font color="#006666">Dim</font></b> <font color="#006666">d1</font>.date2(5)
  
<font color="#006666">  d1</font>(0)\s = "05.04.2008"
<font color="#006666">  d1</font>(1)\s = "07.05.2009"
  
  <b><font color="#006666">Debug</font></b> <font color="#006666">d1</font>(0)\d\day
  <b><font color="#006666">Debug</font></b> <font color="#006666">d1</font>(0)\d\month
  <b><font color="#006666">Debug</font></b> <font color="#006666">d1</font>(0)\d\year
  
  <b><font color="#006666">Debug</font></b> <font color="#006666">d1</font>(1)\d\day
  <b><font color="#006666">Debug</font></b> <font color="#006666">d1</font>(1)\d\month
  <b><font color="#006666">Debug</font></b> <font color="#006666">d1</font>(1)\d\year
    
  d2.date2\s = "15.11.2010"
  
  <b><font color="#006666">Debug</font></b> d2\d\day
  <b><font color="#006666">Debug</font></b> d2\d\month
  <b><font color="#006666">Debug</font></b> d2\d\year
</font></pre>

</blockquote><p><b>Example:</b> Alignment</p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> Type <b><font color="#006666">Align</font></b> 4
    Byte.b
    Word.w
    Long.l
    Float.f
  <b><font color="#006666">EndStructure</font></b>
  
  <b><font color="#006666">Debug</font></b> <font color="#006666">OffsetOf</font>(Type\Byte)   <font color="#006666">; will print 0</font>
  <b><font color="#006666">Debug</font></b> <font color="#006666">OffsetOf</font>(Type\Word)   <font color="#006666">; will print 4</font>
  <b><font color="#006666">Debug</font></b> <font color="#006666">OffsetOf</font>(Type\Long)   <font color="#006666">; will print 8</font>
  <b><font color="#006666">Debug</font></b> <font color="#006666">OffsetOf</font>(Type\Float)  <font color="#006666">; will print 12</font>
</font></pre>


</blockquote><p><b>Example:</b> Pointers</p><blockquote>


<pre><font face="Courier New, Courier, mono"size="2">  <b><font color="#006666">Structure</font></b> Person
    *Next.Person <font color="#006666">; Here the '*' is mandatory to declare a pointer</font>
    Name$
    Age.b
  <b><font color="#006666">EndStructure</font></b>

  Timo.Person\Name$ = "Timo"
  Timo\Age = 25
  
  Fred.Person\Name$ = "Fred"
  Fred\Age = 25
  
  Timo\Next = @Fred <font color="#006666">; When using the pointer, the '*' is omitted</font>
  
  <b><font color="#006666">Debug</font></b> Timo\Next\Name$ <font color="#006666">; Will print 'Fred'</font>
</font></pre>

</body></html>